https

Type

keyword

Summary

Used as a URL type with such commands as put and get to designate a file on the World Wide Web.

Syntax

https

Description

Use the http keyword to work with files on the Web.

The URL scheme "http" indicates information located on a web server. An http URL consists of:

1. The string "https://"
2. An optional user name and password, separated by a colon (:)

   and followed by \"@\"
3. The name of the server (for instance, \"example.net\") followed
   by a slash
4. The location of the resource (often, a file path).

Here are some examples of valid https URLs:

• 'https://www.example.com\' : The main page for the server "www.example.com"
• 'https://www.example.com/directory/\' : A directory on the server
• 'https://www.example.com/directory/file.html\' : A file on the server
• 'https://user:password@www.example.com/file.txt\' : A file accessed by

   a user name and password
* \'https://www.example.com/directory/stuff.html?list=yes\' : A page 
   generated by a query - possibly generated by a CGI

Important

If your user name or password contains any of the characters ":", "@", "/", ".", or "|", use the URLEncode function to safely encode the user name or password before putting them into the URL. The following example constructs a URL for a user whose password contains the "@" character:

    put \"name\" into userName
    put \"jdoe@example.com\" into userPassword
    put \"https://\" & userName & \":\" & URLEncode(userPassword) \
        & \"@www.example.net/index.html\" into fileURLToGet
    get URL fileURLToGet

An http URL is a container, and you can use the expression URL httpURL in any statement where any other container type is used. When you get the value of an http URL, LiveCode downloads the URL from the server. (If you have previously cached the URL with the load command, it fetches the URL from the cache.)

note

Transferring a URL by using it in an expression is a blocking operation: that is, the handler pauses until LiveCode is finished getting the URL. Since contacting a server may take some time due to network lag, URL operations may take long enough to be noticeable to the user.

The following example shows how to set a flag in a global variable to prevent multiple downloads. The variable "gDownloadInProgress" is set to true while a download is going on, and back to false when the download concludes. If the user clicks the button again while the download is still going on, the handler simply beeps:

    on mouseUp
        global gDownloadInProgress
        if gDownloadInProgress then
            beep
            exit mouseUp
        end if
        put true into gDownloadInProgress -- about to start
        put URL (field \"Page to get\") into field \"Command Result\"
        put false into gDownloadInProgress -- finished
    end mouseUp

For technical information about URLs and the https URL scheme, see RFC 1630.

Important

The https keyword is part of the Internet library on desktop platforms. To ensure that the keyword works in a desktop standalone application, you must include this custom library when you create your standalone. In the Inclusions pane of the Standalone Application Settings window, make sure the "Internet" script library is selected.

Cross-platform note

On iOS and Android, you can use the https keyword without the need for the Internet library. When specifying URLs for iOS and Android, you must use the appropriate form that conforms to RFC 1630.

Examples

set the htmlText of field 1 to URL "https://example.org/data.html"

put URL "https://www.example.com/output?this=that" into testData

put line 2 of URL "https://www.example.com/stuff/" into testDate

Value

Name	Type	Description
the result		If an error occurs during transfer of the data, the error is placed in the result function. The first word returned by the result function is "error", followed (where appropriate) by the text of the error message returned by the HTTP server, including the server response code. Important: If there is an error downloading an https URL, the URL container does not necessarily evaluate to empty. Most HTTP servers send an error page when the file is not found or another error occurs, and the URL container will evaluate to the contents of this page. Before using the data in a URL container, check the result to make sure it is empty and there was no error. Important: If a blocking operation involving a URL (using the put command to upload a URL, the post command, the delete URL command, or a statement that gets an ftp or HTTP URL) is going on, no other blocking URL operation can start until the previous one is finished. If you attempt to use a URL in an expression, or put data into a URL, while another blocking URL operation is in progress, the result is set to "Error Previous request not completed". Downloading a URL does not prevent other messages from being sent during the download: the current handler is blocked during the download, but other handlers are not. This means that if, for example, your application has a button that downloads a URL, the user might click the button again (or click another button that downloads another URL) while the first URL is still being downloaded. In this case, the second download is not performed and the result is set to "error Previous request has not completed." To avoid this problem, you can set a flag while a URL is being downloaded, and check that flag when trying to download URLs to make sure that there is not already a current download in progress.

Related

command: post, put, load, group, delete URL, get, libURLSetCustomHTTPHeaders

control structure: function

function: result, files, libURLErrorData, value

glossary: LiveCode custom library, application, standalone application, evaluate, server, blocking, cache, statement, URL, command, container, expression, main stack, keyword, Standalone Application Settings, upload, download, message, flag, handler

keyword: URL, file, ftp, button, word, http

library: Internet library, library

message: startup, openBackground, preOpenStack, openStack, preOpenCard

Compatibility and Support

Introduced

LiveCode 2.5

OS

mac

windows

linux

ios

android

Platforms

desktop

server

mobile